home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / datecls.exe / DATECLS4.DOC < prev    next >
Text File  |  1993-03-07  |  15KB  |  349 lines
  1. =======================================================
  2. Documentation for "The Killer Date Class!" Version 4.00
  3. =======================================================
  4.  
  5. History
  6. =======
  7. In the beginning Steve Marcus (CIS 72007,1233) posted a basic date
  8. manipulation/arithmetic class produced with Borland C++ 2.0 in the 
  9. BPROGB forum, with a request for suggestions and enhancements. This was
  10. on 6/19/91.
  11.  
  12. A rather enterprising gentleman by the name of Eric Simon (CIS 70540,1522)
  13. accepted the challenge, and produced a new and improved version in the 
  14. course of a project he was developing at work. He contributed the results
  15. to the forum on 6/29/91, also inviting enhancements and comments.
  16.  
  17. About that time yet another enterprising gentleman named Christopher Hill
  18. developed a need for a universal date conversion routine for use in a
  19. business project he was developing as well.  Browsing the same forum, he
  20. encountered Eric's class, which provided much of the functionality he needed
  21. - the basic julian-gregorian and day of week conversion algorithms -
  22. relieving him of the task of researching or re-inventing them. Eric had also
  23. added overloaded + and - operators for incrementing date objects by integer
  24. days, as well as several print functions.  Chris needed additional features
  25. for his implementations, thus was born versions 3.0 and 3.1(Hill & Simon).
  26.  
  27. Well, almost a year later I sent out an SOS for a date class so _I_ didn't
  28. have to re-invent the wheel and lo-and-behold Chris responded.  Thus begins
  29. the saga of version 4.0!  I would like to take this opportunity to do a
  30. little witnessing: I looked all over for a date class that would suit my
  31. needs!  I reviewed many implementations from strangers and friends alike
  32. and I am here to tell ya' folks, "It don't 'git no bedder 'n dis!"  This
  33. class is _VERY_ cool!  Now I'm not trying to say that there's no more
  34. room for enhancements (I'd really be crazy then!), but I am saying that if
  35. your looking for a _GOOD_ date class (I'd say commercial quality because
  36. I have yet to see a commercial product that implemented a date class to
  37. my satisfaction!) then this is it!  So jump in and add to it, make it
  38. better and we'll SAVE THE WORLD!  (Ok, so I got a little carried away at
  39. the end. Just a little...)
  40.  
  41. No, but really...
  42. This is a truly pleasing example of co-operation among professionals, and
  43. an "object" study in the code reusability of OOP, resulting in three releases
  44. of one class within a single month by three different analysts who have never
  45. met, and yet another upgrade almost a year later by a fourth analyst (myself)
  46. and none of us have yet to meet!  Chris thanks Steve and Eric for their
  47. inspiration and generousity, and I thank all three as well and hereby
  48. contribute my additions to the public domain.
  49.  
  50. I believe any of us would welcome further comments, suggestions and
  51. enhancements as well.
  52. Good luck!  May the quest for the perfect date class continue!
  53.  
  54.    v4.1  Kenneth A. Argo  - 71241,3635   3/7/93
  55.    v4.0  Charles Price    - 70541,3651   6/27/92
  56.    v3.1  Hill & Simon     -              8/05/91
  57.    v3.0  Christopher Hill - 72030,2606   7/11/91
  58.    v2.0  Eric Simon       - 70540,1522   6/29/91
  59.    v1.0  Steve Marcus     - 72007,1233   6/16/91
  60.  
  61.  
  62. Implementation Notes
  63. ====================
  64.    All versions prior to 4.0 were written specifically for a Borland C++
  65.    compiler.  However, version 4.0 was written specifically for
  66.    Microsoft C++ 7.0.  I too have attempted to optimize the code including
  67.    the specification of const where applicable, the passing of references
  68.    where advisable, and the use of constructor initializers where needed.
  69.    However, I have not made an exhaustive analysis of this subject either.
  70.  
  71.    To get the best overview of the class capabilities run the demo program.
  72.    It may not look pretty, but with a printout of a sample run and the code
  73.    you should be able to get a really good feel for it.  I have included a
  74.    samples run at the end of this file in case someone doesn't want to
  75.    take the time to compile the demo program.
  76.  
  77.    This ZIP file contains:
  78.  
  79.       DATECLS4.DOC   -   this file
  80.       DATECLS4.H     -   the header file
  81.       DATECLS4.CPP   -   the member functions
  82.       DATEDEMO.CPP   -   a test program (and a messy one at that!)
  83.       DATECLS4.LIB   -   a lib file so you can use it even if you
  84.              don't have MSC7.0, or you just don't feel
  85.              like fussin' with it!  (Added in v4.0)
  86.  
  87.  
  88. Future possibilities for enhancement include
  89. ============================================
  90.     
  91.    1. Adding a derived Time class, for those applications which require
  92.       the ability to track more than just dates. This would allow the
  93.       manipulation of times for all dates (not just since 1980), and
  94.       arithmetic calculations as well.
  95.  
  96.  
  97. Additions/Changes to Version 4.1
  98. ================================
  99.  
  100. Fixed date display when using the * operator to get a string pointer.
  101.   The code would return xx/xx/  xx if you only supplied a 2 digit year.
  102. Optimized the * operator so Invalid Dates would use a common "invalid date"
  103.   text pointer.
  104. Fixed the +, - and * operators to get rid cases where memory leaks would
  105.  occur.
  106. Fixed some variable casts so the code can be compiled with /W4
  107. Added a destructor tp delete items created dynamically on behalf of the
  108.  object (ie. char *).
  109.  
  110. Release Documentation for Version 4.0
  111. =====================================
  112. Most of the modifications made to version 3.1 were to expand the public
  113. interface.  Below is a list of new features in v4.0:
  114.  
  115.     1. Date &Set() - Sets self to current system date; this may also be
  116.          accomplished by passing initializing a date object like so:
  117.          Date oDate1("Today");  // See demo for examples
  118.  
  119.     2. Date &Set(long lJulian) - Sets self to the specified julian date
  120.  
  121.     3. Date &Set(int nMonth, int nDay, int nYear) - Sets self to specified
  122.          month, day, and year.  The year must be 4 numbers long, not 2.
  123.  
  124.     4. Date &AddWeeks(int nCount = 1) - Add or subtract(use a negative int)
  125.          a specified number of weeks to/from self
  126.  
  127.     5. Date &AddMonths(int nCount = 1) - Add or subtract(use a negative int)
  128.          a specified number of months to/from self
  129.  
  130.     6. Date &AddYears(int nCount = 1); - Add or subtract(use a negative int)
  131.          a specified number of years to/from self
  132.  
  133.     7. int   Day() const - Returns numeric day of the month for self
  134.     8. int   DaysInMonth() - Returns number of days in month (1..31)
  135.     9. int   FirstDOM() const - Returns the First Day Of Month for self as a
  136.          numeric (1..7)
  137.  
  138.    10. char *CDOW() - Returns character Day Of Week ('Sunday'..'Saturday')
  139.    11. int   NDOW() const - Returns the numeric day of the week for self(1..7)
  140.  
  141.    12. int   WOM() - Returns numeric Week Of Month  (1..6)
  142.    13. int   WOY() - Returns numeric Week Of Year   (1..52)
  143.  
  144.    14. char *CMonth() - Character Month name ("January")
  145.    15. int   NMonth() const - Month Number (1..12)
  146.  
  147.    16. Date  BOM() - Returns a new date object that is the First Date Of
  148.          the Month in self.  For example:
  149.         Date oDate1;
  150.         Date oDate2("Today");
  151.         oDate1 = oDate2.BOM();
  152.  
  153.    17. Date  EOM() - Returns a new date object that is the Last Date Of
  154.          the Month in self.  (See example in 16 above)
  155.  
  156.    18. int   NYear4() const - Returns the numeric value of the year for self
  157.          in the form 1992.
  158.  
  159.    19. Date  BOY() - Returns a new date object that is the First Date Of
  160.          the Year in self. (See example 16 above)
  161.  
  162.    20. Date  EOY() - Returns a new date object that is the Last Date Of
  163.          the Year in self. (See example 16 above)
  164.  
  165.    21. Added overloaded operators for + and - to accept int's.
  166.    22. Added overloaded operators for ++ and -- for Postfix notation
  167.  
  168.    23. Switched from the Borland style DOS date structure(date) to the
  169.        Microsoft version(_dosdate_t).
  170.  
  171. Suggestions and general comments are always welcome!
  172. Enjoy!  Chuck :-}
  173.  
  174.  
  175.  
  176. Release Documentation for Version 3.1
  177. =====================================
  178. Subsequent to release 3.00, we (Hill & Simon) decided to co